feat: per-company plugin enablement - #255

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work.
• Plugins act on behalf of companies (running agent tools, handling company-scoped events, contributing UI), and the schema already has a per-company plugin_company_settings.enabled column for this.
• That column is dormant: plugin enablement is effectively instance-global today — once an instance admin installs a plugin, every company gets it with no way to opt out, and there is no manifest-level mechanism for a plugin author to require instance-admin control over which companies get it (needed by governance-style plugins like billing).
• This gap blocks any plugin that needs to be mandatory-but-admin-controlled rather than a company self-service toggle, and leaves company owners with no UI to manage which of the instance's installed plugins their company actually uses.
• This pull request activates the dormant per-company switch: a manifest companyEnablement declaration (default: "on"|"off", optional locked), a plugins:manage permission, catalog/enablement routes with a write-time lock guarantee, six enforcement points across the plugin-hosting surface, and a company-facing "Plugins" settings page.
• The benefit is a real two-switch model (instance install × company enablement) that supports both opt-in company plugins and instance-mandated ones, unblocking the standing-gate and billing-plugin work stacked on top of this branch.

Linked Issues or Issue Description

Fixes #258

No pre-existing public issue tracks this; describing in-PR per the feature-request template. This branch deliberately converges with the pre-existing contrib/company-plugin-enablement branch (see CONTRIBUTING.md → search-first); at implementation time we diffed against it and reused matching enforcement wiring and authz tests where they lined up. Refs the earlier branch as related prior art: contrib/company-plugin-enablement.

Problem or motivation
plugin_company_settings.enabled exists in the schema but nothing reads or writes it — plugin enablement is instance-global in practice. There is no way for a company to disable a plugin it doesn't want, and no way for an instance admin to install a plugin that is mandatory for every company but still tracked per-company (e.g. so a later admin override or audit trail is meaningful).

Proposed solution
Add an optional manifest field companyEnablement: { default: "on" | "off", locked?: boolean } (absent ⇒ "on", today's behavior, zero impact on existing plugins). locked: true renders as a non-interactive "Managed by instance" entry — only an instance admin can override it per company. Add GET /plugins/companies/:companyId/catalog and PUT /plugins/:pluginId/companies/:companyId/enablement (409 on a locked plugin), gated by a new plugins:manage permission (implicit for company owner/admin, grantable via principal_permission_grants); catalog reads additionally require the company.plugins surface (PR-1). Centralize the actual enablement check in one helper, isPluginEnabledForCompany(pluginId, companyId), and apply it at all six places a plugin currently acts for a company: host-services company resolution, bridge data/action calls, event-bus delivery, agent-tool dispatch, plugin-scoped API routes, and ui-contributions slot filtering. Ship a company "Plugins" settings page (surface company.plugins) with catalog + toggle + mobile nav entry.

Alternatives considered
Leaving enablement instance-only (status quo) was rejected — it cannot support governance-style plugins (billing) that must be mandatory yet still track state per company, and gives companies no self-service control over optional plugins. A per-route ad hoc check at each of the six call sites (instead of one shared helper) was rejected as a correctness risk — a missed call site would silently leave a "disabled" plugin acting for a company; the single helper plus per-gate enforcement tests close that hole deliberately.

Roadmap alignment
Checked ROADMAP.md — generic core plugin-lifecycle primitive, upstreamable, not overlapping planned core work. Full design at docs/superpowers/specs/2026-07-18-settings-visibility-and-plugin-enablement-design.md §4.

What Changed

• Manifest schema: companyEnablement?: { default: "on" | "off"; locked?: boolean }, validated with .strict() on the sub-schema.
• New permission key plugins:manage in PERMISSION_KEYS; implicit for owner/admin company memberships, grantable to other principals.
• GET /plugins/companies/:companyId/catalog — installed + ready + catalog-eligible plugins with { enabled, locked, defaultEnabled, hasCompanySettingsPage }; sandbox-provider/credential-broker infra plugins stay excluded via existing categories.
• PUT /plugins/:pluginId/companies/:companyId/enablement — { enabled }; 409 for locked plugins; write-time lock guarantee verified (host-services upsert path cannot silently enable a disabled/locked plugin — see plugin-host-services.ts localFolders.configure call site, confirmed unreachable for gated plugins).
• isPluginEnabledForCompany(pluginId, companyId) helper in plugin-company-enablement.ts, applied at all six enforcement points: host-services company resolution, bridge data/actions, event-bus delivery, agent-tool dispatch, plugin-scoped API routes (companyResolution), and ui-contributions slot filtering.
• Company "Plugins" settings page (company.plugins surface): catalog list, toggle, capability summary, link into an enabled plugin's companySettingsPage; mobile CompanySettingsNav entry added (initially missed, caught in review).
• OpenAPI spec updated for catalog/enablement routes.

Verification

• cd server && pnpm typecheck — 0 errors.
• Enablement-helper unit tests: default on/off × existing-row states, full matrix.
• Authz tests: plugins:manage required for toggle, viewer denied, locked plugin returns 409, catalog read requires company.plugins surface exposure.
• One enforcement test per gate point (6/6), including the PUT-route ungated-write regression found in final review (host-services localFolders path) and the launchers/PluginPage company-filter gap found in the same pass — both fixed and re-verified.
• Slot-filtering UI test: disabled-plugin slots never reach a company's ui-contributions.
• Toggle round-trip and cross-company PUT-isolation tests.
• 15 commits on feat/company-plugin-enablement, base feat/settings-surface-policy; final whole-branch review closed "with fixes" and re-verified.

Risks

• Base branch: stacked on feat/settings-surface-policy (PR-1) — this PR only makes sense merged after PR-1, and inherits PR-1's capabilities/surface-gate plumbing. Diff against main will include PR-1's changes until PR-1 merges; review the PR-1-vs-PR-2 diff range, not the full branch diff.
• Backward compatible by construction: manifest field is optional and absent ⇒ "on", so every existing installed plugin keeps today's instance-global behavior with no data migration.
• The write-time lock guarantee (a locked plugin can never be silently enabled via a different code path) was the main risk surface here — closed by an explicit gate ordering fix plus a dedicated regression test rather than by inspection alone.
• Minor known follow-ups, not blocking: duplicated forbidden() throw in plugin-company-enablement.ts (DRY candidate), a redundant getById per gated call (efficiency, not correctness), and a missing toggle-error-path UI test — tracked for follow-up, not this PR's scope.
• Default-off cron jobs still fire instance-level regardless of company enablement — spec-consistent (jobs are instance infrastructure, not company-scoped actions) but worth reviewer awareness.

Model Used

Claude (Anthropic), Sonnet 5 (model id claude-sonnet-5) driving Claude Code's subagent-driven SDD workflow — spec-driven task briefs, extended multi-step tool use, and an independent code-review pass per task, plus a dedicated whole-branch final review before merge.

Screenshots

CompanyPlugins catalog — locked plugin row

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs)
• My branch name describes the change (e.g. docs/..., fix/...) and contains no internal Paperclip ticket id or instance-derived details
• I have run tests locally and they pass
• I have added or updated tests where applicable
• I have updated relevant documentation to reflect my changes
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge